Summary Manual - Virtual Domains

Virtual Domains

Summary can produce separate reports for each domain you host, or for various portions of a single domain. Each set of reports, for a single domain or portion of a domain, is called a sub-report. Summary supports up to three sub-reports, Summary Pro supports up to 500 sub-reports.

Each sub-report contains an entire set of the reports available on the Report Menu. These reports show information on a subset of all the available log entries. You configure the sub-report to select which log entries belong in this sub-report.

Summary can process a log file generated by a single web server or multiple logs generated by a single or multiple web servers. Each individual log file may contain entries from a single domain or from multiple domains running on the same server. Summary refers to a single domain, out of the collection of all the domains for which you have log files, as a virtual server.

In some cases configuring virtual domains may seems complicated. This is because it can get very complicated. Each brand of server software seems to have their own way of doing things and Summary has to be flexible enough to deal with all of them. Summary can even handle cases where you use a single copy of Summary to report on several different domains running on different brands of server software, where each server stores domain information differently.

A Quick Example
Lets say you are running a web server for three of your friends: Bob, Jane and Bill. Even though you are running a single web server that generates a single log file, Summary can process that log file into three separate sub-reports - one for each of your friends, assuming the server is properly configured. Now Bob has a set of reports that contain information only about his site and Jane has a set of reports for her site, and so on. Obviously, if you are running a commercial web server, you can see why separate sub-reports for each virtual domain is useful to your clients... and profitable for you as a value added option.

Configuring Summary Virtual Domains
Summary provides multiple ways to detect each virtual domain and split them up into subreports. There are four common approaches to detecting which virtual domain a log entry is associated with.

Method one: information in the requested URL (i.e. the path starts with /~bob or /~jane) (common configuration for WebStar)
Method two: the host name as the client typed it into the browser, from the HTTP 'Host' header
Method three: the host name as configured on the server (common configuration for Microsoft IIS)
Method four: separate log files for each virtual domain (common configuration for Apache)

Method One
The first method is to determine the virtual domain from the requested URL path. For example, requests starting with http://www.mydomain.com/~bob/ and http://www.mydomain.com/~jane/ can be split out into separate sub-reports. This can be used when you don't actually have separate domains names, you just want to report on different parts of your site separately. This is also commonly used with WebSTAR because WebSTAR will add the internal folder name to a request before logging it. For example WebSTAR might log a request to http://www.bob.com/index.html as /bob/index.html. The exact folder names WebSTAR adds depend on your WebSTAR configuration.

To configure Summary in this situation you enter the leading portion of the request, followed by a '*' into the 'Files included in this Sub-report' field and enter a '*' into 'Servers to include in this Sub-report'. For example, to get all request that start with '/bob/' you would enter '/bob/*' into 'Files included in this Sub-report'. If you are not sure what names WebSTAR is adding to the request you can take a look at the Directory Report or at your WebSTAR configuration settings.

Method Two
The second method is to determine the virtual domain from the host name the client entered into their browser. For this approach to work, your server must be logging the HTTP Host header. First, you need to determine all of the different host names that will lead to your web site. There are frequently several different names which will access a single site. For example, summary.net, www.summary.net, and 209.163.232.96 will all take you to the Summary web site. Enter all of the domain names that lead to your site into the 'Servers to include in this Sub-report'. Enter a '*' into the 'Files included in this Sub-report' field.

WebSTAR will log this information if you include the CS(HOST) log token in the log format. If you are not sure which domain names to use, take a look at the Virtual Servers report in a sub-report that includes all log entries. It will show you what domain names occur in your log file. If the report is blank your server is probably not configured to log this information.

Method Three
The third method is to use the server name as configured on the server to determine the virtual domain. For this approach to work, your server must be logging the server name. Enter the server name into the 'Servers to include in this Sub-report' field. Enter a '*' into the 'Files included in this Sub-report' field.

Microsoft IIS typically includes this information in the log file. If you are not sure which server name to use, take a look at the Virtual Servers report in a sub-report that includes all log entries. It will show you what server names occur in your log file. If the report is blank your server is probably not configured to log this information.

Method Four
The fourth method is to log each virtual domain into a separate log file. In order to tell Summary which log files go with which virtual domain you need to create sub-folders (sub-directories) inside the Logs folder (log directory on Unix systems). There should be one sub-folder for each virtual domain that you want a separate report for. Put the log files into the corresponding folders. Put the folder name into the 'Servers to include in this Sub-report' field. Enter a '*' into the 'Files included in this Sub-report' field.

Apache typically uses this approach, creating a separate log file for each domain. You can also use this approach any time you have separate log files for each virtual domain you want reports for.

Solving Configuration Problems?
When debugging virtual server configurations it is often handy to make a sub-report that reports on all entries in all log files. Set both 'Servers to include in this Sub-report' and 'Files included in this Sub-report' to '*'. You can then look at the Virtual Server report to see what values occur for the virtual server name or the Directory Report to see which directory names are actually in use.

Configuring Virtual Domains for use with WebSTAR
WebSTAR always logs all requests to a single log file. You can configure WebSTAR to log the virtual server name by adding the CS(HOST) token to the log format. Summary reports this name, typically the DNS name of the server, as the "server name". With this log token included, Summary can select log entries for inclusion in a sub-reports based on this name. Typically a single virtual domain can appear with several different names. This means that you will have to include all of the possible names for the server in the "Servers to include in this sub-report". For example summary.net can appear as summary.net or www.summary.net.

WebSTAR always adds the name of the root folder to the front of all requests to virtual servers. For example if I have a virtual domain called virtual.summary.net and have configured WebSTAR to fill all requests to that domain from the "virtual" folder, it will log a request to <http://virtual.summary.net/home.html> as a request to "/virtual/home.html". You can then use the folder name to select which log entries are to be included in a sub-report. In this case you would set "Files included in this Sub-report" to "/virtual/*".

Configuring Virtual Domains for use with Apache
Apache is usually configured is to send each virtual domain into a separate log file. We strongly recommend using this approach. It is possible to configure Apache to record all log entrees for all virtual domains into a single log file, but if you decide to do this there will be complications. There is no log file format that includes the server name or host name in the log file that is supported by Apache and automatically read by Summary. Further, if you neglect to include the server or host name in the log format file, your log files are worthless because no one will have any way to distinguishing which log entries belong with which virtual domain.

When you are using separate log files for each virtual domain you need to tell Summary which log file comes from which virtual server. To do this, make a folder (directory) for each virtual server inside the Logs folder (log directory), name the folder with the name of the virtual server, then put the logs from each virtual server into the corresponding folder. Summary will take the folder name and use it as the server name. You can then configure a sub-report by setting "Servers to include in this Sub-report" to the folder name.

If you want to have a single log file with entries from all of your domains, you are going to need to add the server name to each log entry and make a custom log format string for Summary. The best place to put the server name is replacing the second field of NCSA Common or NCSA Combined format log files. The "indent" field (the second field) is never used anymore, it used to be the users e-mail address but privacy concerns caused it to be disabled on all browsers. The Apache configuration for NCSA Combined format with the host name in the second field is:

LogFormat "%h %v %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-agent}i\"

The custom user log format string to configure Summary to read that format is:

HOST SERVER USER DATE-CLF REQUEST STATUS BYTES IF-EOL REFERER AGENT

Configuring Virtual Domains for Microsoft IIS
Microsoft IIS will typically log the 'server name', a name given to each virtual server during configuration. If the log format you are using includes this field you can use it to select virtual domains.

Microsoft IIS supports three log formats:

NSCA common format - don't use this log format with virtual domains, it does not contain the server name
Microsoft format - always includes server names
W3C ExLF - you need make sure the 'Server Name' field is turned on

Other Servers
All servers will work with one of the four methods presented above. Some web servers use NCSA Common or NCSA Combined log format but they replace the second token of each line with the HTTP Host name. Summary does not directly support this log format, but can be told how to read that format. On the Miscellaneous configuration page, set 'User log format definition' to:

HOST SERVER USER DATE-CLF REQUEST STATUS BYTES IF-EOL REFERER AGENT

Auto Configure
Summary also features an auto configure option. There is a link to Auto Configure located at the bottom of the main configuration page. When Auto Configure is selected Summary will attempt to suggest meaningful subreport settings based on results from the most recent log processing run.

To use auto configure, you will need to process the logs with at least one sub-report that includes all of the log entrees (this is the default configuration). Auto Config will then search for virtual server names and directory names and propose various sub-reports. You simply check off the ones you want. You still need to re-process the logs to get the sub-reports to contain information.

Why not use auto configure all the time? The problem with auto configure is that it may suggest things you don't want. Auto configure can make intelligent suggestions - up to a point. For example, it does not know which server software you are using. Therefore, it has a habit of suggesting normal directories are virtual servers. It will only suggest 50 at a time, and it won't suggest ones you already have.

Using Sub-Reports
If Summary is running on the same machine as your main server, you should be able to access Summary by any of the domain names you are hosting with the :8000 port number (or whatever port you have configured Summary to use) added. To go directly to a specific report you would type <http://their.domain:8000/~name> where 'name' is the string entered in "Identifier for use in report URLs" for their sub-report.

If you give each sub-report a different name and password you can skip the ~name part and Summary will find the correct sub-report from the name and password.

Password Protection of Sub-reports
Sub-reports can be name and password protected. If there is a configuration name/password and the first sub-report is name/password protected, the name and password entered will be used to automatically select the correct sub-report. A sub-report can also be given an "Identifier for use in report URLs". This identifier can be used to go directly to a specific sub-report by appending '~' (or '.' or '$') and the identifier to the URL Summary gives when it starts up. For example if Summary is at "http://my.computer.com/" and you have a sub-report with the id 'james', you would use the URL "http://my.computer.com/~james" to directly access that sub-report.